package com.gitee.helioz.openai.api.endpoint.files;

import com.gitee.helioz.openai.api.dto.files.FileDTO;
import com.gitee.helioz.openai.api.dto.DeleteResponse;
import com.gitee.helioz.openai.api.dto.files.FileResponse;
import com.gitee.helioz.openai.api.dto.files.FileUploadRequest;

/**
 * 〈文件服务〉
 *
 * @author <a href="https://gitee.com/helioz">Morning Starr</a>
 */
public interface FileService {

    /**
     * 获取属于其组织的文件列表
     * <p><a href="https://platform.openai.com/docs/api-reference/files">文档</a></p>
     *
     * @return 响应对象
     */
    FileResponse list();

    /**
     * 上传文件，目前，一个组织上传的所有文件的大小限制为最多1 GB。
     * <p><a href="https://platform.openai.com/docs/api-reference/files/upload">文档</a></p>
     * @param fileRequest 请求对象
     * @return 响应对象
     */
    FileDTO upload(FileUploadRequest fileRequest);

    /**
     * 删除文件
     * <p><a href="https://platform.openai.com/docs/api-reference/files/delete">文档</a></p>
     * @param fileId 文件ID
     * @return 响应对象
     */
    DeleteResponse delete(String fileId);

    /**
     * 获取文件信息
     * <p><a href="https://platform.openai.com/docs/api-reference/files/retrieve">文档</a></p>
     * @param fileId 文件ID
     * @return 响应对象
     */
    FileDTO retrieve(String fileId);

    /**
     * 获取文件内容
     * TODO: 不知道响应体类型
     * <p><a href="https://platform.openai.com/docs/api-reference/files/retrieve-content">文档</a></p>
     * <p>注意：免费账户无法下载用于fine-tune训练的文件</p>
     * @param fileId 文件ID
     * @return 响应对象
     */
    String retrieveContent(String fileId);
}
